//
//  "$Id: AudioOut.h 91860 2012-12-08 09:18:30Z li_weijun $"
//
//  Copyright (c)1992-2008, ZheJiang Dahua Technology Stock CO.LTD.
//  All Rights Reserved.
//
//	Description:	
//	Revisions:		Year-Month-Day  SVN-Author  Modification
//

#ifndef __AUDIO_OUT_API_H__
#define __AUDIO_OUT_API_H__

#include "Types.h"
#include "AudioIn.h"

#ifdef __cplusplus
extern "C" {
#endif

/// \defgroup AudioOutAPI API Audio Output 
/// 音频输出接口
/// \n 调用流程图:
/// \code
///    ================================
///               |
///     getAudioOutputChannels
///               |
///       createAudioOutput
///               |
///            addRef
///               |-----------+
///             output     setVolume
///               |-----------+
///            release
///               |
///    ================================
/// \endcode
/// @{

/// 音频输出属性信息
typedef struct AudioOutAttr 
{
  char pcAudioNode[32];
  SampleFormat enSampleFormat;
  unsigned int u32Channels;
  unsigned int u32SampleRate;
  unsigned int u32NbSamples;
} AudioOutAttr;


/// 音频输出能力结构，128字节
typedef struct AudioOutCaps
{
	char mixing;		///< 是否支持混音
	char reservedb[3];	///< 保留
	int reserved[31];	///< 保留
}AudioOutCaps;

/// 音频输出接口，512字节
typedef struct AudioOutput
{
	/// 底层私有数据
	void *priv;


	/// 增加接口引用
	int (*addRef)(struct AudioOutput *thiz);


	/// 释放接口
	int (*release)(struct AudioOutput *thiz);


	/// 得到音频输出支持的特性。
	///
	/// \param [in] thiz 本对象指针
	/// \param [out] caps 指向音频输出特性结构AudioOutCaps的指针。
	/// \retval 0  获取成功。
	/// \retval <0  获取失败。
	int (*getCaps)(struct AudioOutput *thiz, AudioOutCaps * caps);


	/// 将音频源合成到音频输出。如果输出设备支持混音，则可以将多路源同时输出；
	/// 否则需要根据具体业务，先禁止输出优先级低的音频源，仅输出优先级最高的
	/// 音频源。
	/// \note 这里接口仅仅用于建立数据连接，相当于套接字函数connect，不能直接
	/// 填充数据。这个接口通过AudioSource在AudioOut和AudioDec或AudioIn之间建立
	/// 连接，连接建立后，音频源数据就可以源源不断地自动被输出。
	///
	/// \note 这里接口仅仅用于建立数据连接，相当于套接字函数connect，不能直接
	/// 填充数据。这个接口通过AudioSource在AudioOut和AudioDec或AudioIn之间建立
	/// 连接，连接建立后，音频源数据就可以源源不断地自动被输出了。
	/// \param [in] thiz 音频输出接口指针
	/// \param [in] source 音频源指针
	/// \param [in] enable 0-禁止该源，1-输出该源。
	/// \retval <0 切换失败
	/// \retval 0 切换成功
	int (*output)(struct AudioOutput *thiz, AudioSource* source, int enable);


	/// 设置音频输出的音量
	///
	/// \param [in] thiz 音频输出接口指针
	/// \param [in] volume 音量，取值0-100，0表示静音
	/// \retval <0 切换失败
	/// \retval 0 切换成功
	int (*setVolume)(struct AudioOutput *thiz, int volume);

    /// 音频输出开启
	int (*start)(struct AudioOutput *pThiz);

	/// 音频输出关闭
    int (*stop)(struct AudioOutput *pThiz);

    /// 设置音频输出属性信息
	/// \param [in] pThiz  音频输出接口指针
	/// \param [in] aoAttr 音频属性信息
	/// \retval <0 失败
	/// \retval 0 成功
    int (*setChnAttr)(struct AudioOutput *pThiz, AudioOutAttr aoAttr);


    /// 发送音频到输出端
	/// \param [in] pThiz 音频输出接口指针
	/// \param [in] pData 音频数据
	/// \param [in] len   音频数据长度
	/// \retval <0 失败
	/// \retval 0 成功    
    int (*sendDataToAo)(struct AudioOutput *pThiz, char *pData, int len);
	
	/// 保留
	int reserved[109];
} AudioOutput;


/// 得到音频输出通道的个数
int PAL_API getAudioOutputChannels();


/// 音频输出接口描述，128字节
typedef struct AudioOutDesc
{
	int	channel;		///< 音频输出物理通道号		
	int	card;			///< 子卡槽位号，0表示主板，>0表示子卡
	int reserved[30];	///< 保留
} AudioOutDesc;


/// 创建音频输出接口
///
/// \param [in] desc 音频输出接口描述结构AudioOutDesc指针
/// \param [out] audioOutput 音频输出接口指针的指针
/// \retval <0 创建失败
/// \retval 0 创建成功
int PAL_API createAudioOutput(AudioOutDesc *desc, AudioOutput **audioOutput);


/// @} end of group

#ifdef __cplusplus
}
#endif

#endif //__AUDIO_OUT_API_H__

